/****************************************************************************
 * Copyright (c) 2024 Qualcomm Technologies International, Ltd
****************************************************************************/
/**
 * \file      dls_kymera_util_if.h
 * \ingroup   support_lib/kymera_utils
 *
 * Kymera utils support lib interface file. <br>
 *
 */

#ifndef _DLS_KYMERA_UTIL_IF_H
#define _DLS_KYMERA_UTIL_IF_H

/*****************************************************************************
Include Files
*/
#include "types.h"
#include "cbops_c.h"

/*****************************************************************************
Public functions
*/

/**
 * Structure holding endpoint time of delivery stats
*/
typedef struct EP_TOD_STATS_INFO {
    TIME     ep_tod;          /* Time of delivery of samples */
    unsigned ep_acc_samples;  /* Accumulated samples from start */
    unsigned ep_id;           /* end point id */
    unsigned ep_hw_latency;   /* number of samples in hw mmu buffer*/
    unsigned ep_mmu_buf_size; /* Total size of mmu buff size */
} EP_TOD_STATS_INFO;

#define EP_TOD_MAX_NUMBER_ENDPOINTS (10)

typedef struct EP_TOD_STATS_INFO_LIST {
    unsigned num_elements;
    EP_TOD_STATS_INFO stats_info[EP_TOD_MAX_NUMBER_ENDPOINTS];
} EP_TOD_STATS_INFO_LIST;

/**
 * \brief Claim a scheduler preemption lock.
 *
 * \param[in]    index         Unused at present. Kept for future use.
 * \return       status        Success or failure of preemption lock 
 */
extern bool sched_preemp_lock_get(unsigned index);

/**
 * \brief Release scheduler’s preemption lock.
 *
 * \param[in]    index         Unused at present. Kept for future use.
 * \return       status        Success or failure of preemption lock 
 */
extern bool sched_preemp_lock_release(unsigned index);


/**
 * \brief Gets the endpoint time of delivery of samples and accumulated samples from the start
 *
 * \param[out]   ep_stats_info         Structure pointer holding time of delivery and accumulated sample count, which gets updated on success.
 * \return       status                Success or failure of ep_stats_info updation.
 */
extern bool ep_tod_stats_get(EP_TOD_STATS_INFO_LIST* ep_stats_info);

/**
 * \brief Gets the endpoint time of delivery of samples and accumulated samples from the start
 *
 * \param[in]   nr_channels   Number of channels.
 * \param[in]   input_idx     Input indices field. 
 * \param[in]   cbops_flags   CBOP flag.
 * \return      cbops_op     cbops operator with render monitor for tod stats.
 */
extern cbops_op* create_pcm_sink_monitor_op(unsigned nr_channels, unsigned* input_idx, unsigned cbops_flags);

/**
 * \brief Gets the endpoint time of delivery of samples and accumulated samples from the start with associated endpoint hooked
 *
 * \param[in]   nr_channels   Number of channels.
 * \param[in]   input_idx     Input indices field. 
 * \param[in]   cbops_flags   CBOP flag.
 * \param[in]   op_data       Operator data which is connected to speaker terminals.
 * \param[in]   terminal_ids  Terminals ids of Speaker
 * \return      cbops_op     cbops operator with render monitor for tod stats.
 */
extern cbops_op* create_pcm_sink_monitor_op_from_ep(unsigned       nr_channels, 
                                                    unsigned*      input_idx,
                                                    unsigned       cbops_flags, 
                                                    void*          op_data,
                                                    unsigned int   terminal_ids[]);

/**
 * \brief Creates the cbuffer and calls cbuffer_clone_sync which makes sure both the clone
 *        buffer and src are in sync soon after creation.
 *        Note: The function caller needs to delete the created buffer after use.  
 *
 * \param[in]   src      The input cbuffer which needs to be cloned.
 * \return      tCbuffer Newly created clone buffer.
 */
extern tCbuffer* cbuffer_clone_create(tCbuffer *src);

/**
 * \brief Synchronizes both src and dst by atomic copy of structure contents.
 *        Here atomic would mean interrupts would be blocked till the execution completes. 
 *
 * \param[in]   src      The source buffer.
 * \param[in]   dst      The destinaton buffer.
 * \return      success (TRUE)/ failure (FALSE).
 */
extern bool cbuffer_clone_sync(tCbuffer *src, tCbuffer *dst);

/**
 * \brief Provides a memory of desired size similar to malloc. This memory
 *        would be available in core dump / mini core dump
 *        Limitation: Size cannot be more than 128 and
 *                    Maximum of 10 unique id is supported
 *                    When an unique id is sent more than once, 
 *                    1st call would get pointer rest all would get null
 * \param unique_id: Malloc unique id for core dump.
 * \param size: Size to be allocated in bytes.
 * \return Pointer (valid address in case of success) / NULL
 */
extern uint32* malloc_debug_info_ptr(int unique_id, int size);

/**
 * \brief Free the reserved memory for unique id.
 * \param unique_id: unique id to be freed.
 */
extern bool free_debug_info_ptr(int unique_id);
#endif